/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.beanutils;

import java.lang.reflect.InvocationTargetException;
import java.util.Map;

/**
 * <p>
 * Utility methods for populating JavaBeans properties via reflection.
 * </p>
 * 
 * <p>
 * The implementations are provided by {@link BeanUtilsBean}. These static utility methods use the default instance. More sophisticated behaviour can
 * be provided by using a <code>BeanUtilsBean</code> instance.
 * </p>
 * 
 * @author Craig R. McClanahan
 * @author Ralph Schaer
 * @author Chris Audley
 * @author Rey Francois
 * @author Gregor Rayman
 * @version $Revision: 690380 $ $Date: 2008-08-29 21:04:38 +0100 (Fri, 29 Aug 2008) $
 * @see BeanUtilsBean
 */

public class BeanUtils {

    // ------------------------------------------------------ Private Variables

    /**
     * The debugging detail level for this component.
     * 
     * Note that this static variable will have unexpected side-effects if this class is deployed in a shared classloader within a container. However
     * as it is actually completely ignored by this class due to its deprecated status, it doesn't do any actual harm.
     * 
     * @deprecated BeanUtils now uses commons-logging for all log messages. Use your favorite logging tool to configure logging for this class.
     */
    private static int debug = 0;

    /**
     * The <code>debug</code> static property is no longer used
     * 
     * @return debug property
     * @deprecated BeanUtils now uses commons-logging for all log messages. Use your favorite logging tool to configure logging for this class.
     */
    public static int getDebug() {
        return (debug);
    }

    /**
     * The <code>debug</code> static property is no longer used
     * 
     * @param newDebug
     *            debug property
     * @deprecated BeanUtils now uses commons-logging for all log messages. Use your favorite logging tool to configure logging for this class.
     */
    public static void setDebug(int newDebug) {
        debug = newDebug;
    }

    // --------------------------------------------------------- Class Methods

    /**
     * <p>
     * Clone a bean based on the available property getters and setters, even if the bean class itself does not implement Cloneable.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean to be cloned
     * @return the cloned bean
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InstantiationException
     *                if a new instance of the bean's class cannot be instantiated
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#cloneBean
     */
    public static Object cloneBean(Object bean) throws IllegalAccessException, InstantiationException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().cloneBean(bean);

    }

    /**
     * <p>
     * Copy property values from the origin bean to the destination bean for all cases where the property names are the same.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param dest
     *            Destination bean whose properties are modified
     * @param orig
     *            Origin bean whose properties are retrieved
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception IllegalArgumentException
     *                if the <code>dest</code> or <code>orig</code> argument is null or if the <code>dest</code> property type is different from the
     *                source type and the relevant converter has not been registered.
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @see BeanUtilsBean#copyProperties
     */
    public static void copyProperties(Object dest, Object orig) throws IllegalAccessException, InvocationTargetException {

        BeanUtilsBean.getInstance().copyProperties(dest, orig);
    }

    /**
     * <p>
     * Copy the specified property value to the specified destination bean, performing any type conversion that is required.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean on which setting is to be performed
     * @param name
     *            Property name (can be nested/indexed/mapped/combo)
     * @param value
     *            Value to be set
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @see BeanUtilsBean#copyProperty
     */
    public static void copyProperty(Object bean, String name, Object value) throws IllegalAccessException, InvocationTargetException {

        BeanUtilsBean.getInstance().copyProperty(bean, name, value);
    }

    /**
     * <p>
     * Return the entire set of properties for which the specified bean provides a read method.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean whose properties are to be extracted
     * @return Map of property descriptors
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#describe
     */
    public static Map describe(Object bean) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().describe(bean);
    }

    /**
     * <p>
     * Return the value of the specified array property of the specified bean, as a String array.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean whose property is to be extracted
     * @param name
     *            Name of the property to be extracted
     * @return The array property value
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#getArrayProperty
     */
    public static String[] getArrayProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().getArrayProperty(bean, name);
    }

    /**
     * <p>
     * Return the value of the specified indexed property of the specified bean, as a String.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean whose property is to be extracted
     * @param name
     *            <code>propertyname[index]</code> of the property value to be extracted
     * @return The indexed property's value, converted to a String
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#getIndexedProperty(Object, String)
     */
    public static String getIndexedProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().getIndexedProperty(bean, name);

    }

    /**
     * Return the value of the specified indexed property of the specified bean, as a String. The index is specified as a method parameter and must
     * *not* be included in the property name expression
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean whose property is to be extracted
     * @param name
     *            Simple property name of the property value to be extracted
     * @param index
     *            Index of the property value to be extracted
     * @return The indexed property's value, converted to a String
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#getIndexedProperty(Object, String, int)
     */
    public static String getIndexedProperty(Object bean, String name, int index) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().getIndexedProperty(bean, name, index);

    }

    /**
     * </p>Return the value of the specified indexed property of the specified bean, as a String.</p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean whose property is to be extracted
     * @param name
     *            <code>propertyname(index)</code> of the property value to be extracted
     * @return The mapped property's value, converted to a String
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#getMappedProperty(Object, String)
     */
    public static String getMappedProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().getMappedProperty(bean, name);

    }

    /**
     * </p>Return the value of the specified mapped property of the specified bean, as a String.</p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean whose property is to be extracted
     * @param name
     *            Simple property name of the property value to be extracted
     * @param key
     *            Lookup key of the property value to be extracted
     * @return The mapped property's value, converted to a String
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#getMappedProperty(Object, String, String)
     */
    public static String getMappedProperty(Object bean, String name, String key) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().getMappedProperty(bean, name, key);

    }

    /**
     * <p>
     * Return the value of the (possibly nested) property of the specified name, for the specified bean, as a String.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean whose property is to be extracted
     * @param name
     *            Possibly nested name of the property to be extracted
     * @return The nested property's value, converted to a String
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception IllegalArgumentException
     *                if a nested reference to a property returns null
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#getNestedProperty
     */
    public static String getNestedProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().getNestedProperty(bean, name);

    }

    /**
     * <p>
     * Return the value of the specified property of the specified bean, no matter which property reference format is used, as a String.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean whose property is to be extracted
     * @param name
     *            Possibly indexed and/or nested name of the property to be extracted
     * @return The property's value, converted to a String
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#getProperty
     */
    public static String getProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().getProperty(bean, name);

    }

    /**
     * <p>
     * Return the value of the specified simple property of the specified bean, converted to a String.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean whose property is to be extracted
     * @param name
     *            Name of the property to be extracted
     * @return The property's value, converted to a String
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @exception NoSuchMethodException
     *                if an accessor method for this property cannot be found
     * @see BeanUtilsBean#getSimpleProperty
     */
    public static String getSimpleProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException {

        return BeanUtilsBean.getInstance().getSimpleProperty(bean, name);

    }

    /**
     * <p>
     * Populate the JavaBeans properties of the specified bean, based on the specified name/value pairs.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            JavaBean whose properties are being populated
     * @param properties
     *            Map keyed by property name, with the corresponding (String or String[]) value(s) to be set
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @see BeanUtilsBean#populate
     */
    public static void populate(Object bean, Map properties) throws IllegalAccessException, InvocationTargetException {

        BeanUtilsBean.getInstance().populate(bean, properties);
    }

    /**
     * <p>
     * Set the specified property value, performing type conversions as required to conform to the type of the destination property.
     * </p>
     * 
     * <p>
     * For more details see <code>BeanUtilsBean</code>.
     * </p>
     * 
     * @param bean
     *            Bean on which setting is to be performed
     * @param name
     *            Property name (can be nested/indexed/mapped/combo)
     * @param value
     *            Value to be set
     * 
     * @exception IllegalAccessException
     *                if the caller does not have access to the property accessor method
     * @exception InvocationTargetException
     *                if the property accessor method throws an exception
     * @see BeanUtilsBean#setProperty
     */
    public static void setProperty(Object bean, String name, Object value) throws IllegalAccessException, InvocationTargetException {

        BeanUtilsBean.getInstance().setProperty(bean, name, value);
    }

    /**
     * If we're running on JDK 1.4 or later, initialize the cause for the given throwable.
     * 
     * @param throwable
     *            The throwable.
     * @param cause
     *            The cause of the throwable.
     * @return true if the cause was initialized, otherwise false.
     * @since 1.8.0
     */
    public static boolean initCause(Throwable throwable, Throwable cause) {
        return BeanUtilsBean.getInstance().initCause(throwable, cause);
    }

    /**
     * Create a cache.
     * 
     * @return a new cache
     * @since 1.8.0
     */
    public static Map createCache() {
        return new WeakFastHashMap();
    }

    /**
     * Return whether a Map is fast
     * 
     * @param map
     *            The map
     * @return Whether it is fast or not.
     * @since 1.8.0
     */
    public static boolean getCacheFast(Map map) {
        if (map instanceof WeakFastHashMap) {
            return ((WeakFastHashMap) map).getFast();
        } else {
            return false;
        }
    }

    /**
     * Set whether fast on a Map
     * 
     * @param map
     *            The map
     * @param fast
     *            Whether it should be fast or not.
     * @since 1.8.0
     */
    public static void setCacheFast(Map map, boolean fast) {
        if (map instanceof WeakFastHashMap) {
            ((WeakFastHashMap) map).setFast(fast);
        }
    }
}
